package cn.song.freight.domain.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

/**
 * 区域树形结构响应DTO
 * <pre>
 * 该数据传输对象用于表示地理区域的树形层级结构，支持三级行政区划：
 * 省份(一级) -> 城市(二级) -> 区县(三级)
 *
 * 主要用途：
 * - 区域选择器的树形展示
 * - 地理位置的层级化管理
 * - 运费策略中区域范围的配置
 *
 * 数据结构特点：
 * - 每个节点包含完整的区域信息（编码、名称、简称）
 * - 通过level字段区分层级（1-省份，2-城市，3-区县）
 * - 通过children字段维护子节点列表，形成树形结构
 *
 * @author SongRenShuo
 * @version 3.0.0
 * @since 2025-08-23
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description = "区域树形结构响应参数")
public class AreaTreeDTO {

    /**
     * 区域唯一标识符
     * 数据库主键，用于唯一标识一个区域节点
     */
    @ApiModelProperty(value = "区域ID")
    private Long id;

    /**
     * 省份编码
     * 全国行政区域代码，唯一标识一个省份
     * 例如：北京市为110000，广东省为440000
     */
    @ApiModelProperty(value = "省份编码")
    private String provinceCode;

    /**
     * 城市编码
     * 全国行政区域代码，唯一标识一个地级市
     * 例如：深圳市为440300，广州市为440100
     */
    @ApiModelProperty(value = "城市编码")
    private String cityCode;

    /**
     * 区县编码
     * 全国行政区域代码，唯一标识一个区县级单位
     * 例如：南山区为440305，福田区为440304
     */
    @ApiModelProperty(value = "区县编码")
    private String districtCode;

    /**
     * 省份名称
     * 省级行政区的完整名称
     * 例如：广东省、江苏省、北京市
     */
    @ApiModelProperty(value = "省份名称")
    private String provinceName;

    /**
     * 城市名称
     * 地级行政区的完整名称
     * 例如：深圳市、广州市、杭州市
     */
    @ApiModelProperty(value = "城市名称")
    private String cityName;

    /**
     * 区县名称
     * 县级行政区的完整名称
     * 例如：南山区、福田区、西湖区
     */
    @ApiModelProperty(value = "区县名称")
    private String districtName;

    /**
     * 省份简称
     * 省级行政区的常用简称，通常用于展示
     * 例如：广东、江苏、北京
     */
    @ApiModelProperty(value = "省份简称")
    private String provinceShortName;

    /**
     * 城市简称
     * 地级行政区的常用简称，通常用于展示
     * 例如：深圳、广州、杭州
     */
    @ApiModelProperty(value = "城市简称")
    private String cityShortName;

    /**
     * 区县简称
     * 县级行政区的常用简称，通常用于展示
     * 例如：南山、福田、西湖
     */
    @ApiModelProperty(value = "区县简称")
    private String districtShortName;

    /**
     * 地址层级标识
     * 标识当前区域节点在树形结构中的层级
     * 取值范围：
     * 1 - 省份层级（根节点）
     * 2 - 城市层级（二级节点）
     * 3 - 区县层级（叶子节点）
     */
    @ApiModelProperty(value = "地址层级：1-省份，2-城市，3-区县")
    private Integer level;

    /**
     * 子区域列表
     * 当前区域节点的下级区域集合，用于构建树形结构
     * 省份节点包含多个城市子节点
     * 城市节点包含多个区县子节点
     * 区县节点此字段通常为空
     */
    @ApiModelProperty(value = "子区域列表")
    private List<AreaTreeDTO> children;
}
